CLAUDE.md 项目规范
一句话理解：CLAUDE.md 就是给 AI 看的 ESLint 配置
作为前端，你一定配过这些文件：
| 你熟悉的 | CLAUDE.md 就是… |
|---|---|
.eslintrc | 给 ESLint 看的规则，告诉它"禁止用 var" |
.prettierrc | 给 Prettier 看的格式，告诉它"缩进用 2 空格" |
tsconfig.json | 给 TypeScript 看的配置，告诉它"开启严格模式" |
CLAUDE.md | 给 Claude 看的规则，告诉它"禁止用 any""用 pnpm""提 PR 前跑测试" |
同理：
| 你熟悉的 | CLAUDE.md 也有类似的 |
|---|---|
package.json 的 scripts | CLAUDE.md 的常用命令（pnpm dev、pnpm test） |
README.md | 项目概述和技术栈 |
.editorconfig | 编码风格和命名约定 |
.eslintignore | .claude/rules/ 的 paths 按目录限定规则 |
~/.npmrc（用户级 npm 配置） | ~/.claude/CLAUDE.md（用户级，所有项目生效） |
本质上做的是同一件事——把规范写成配置文件，让工具自动遵守。只不过以前是给机器工具配，现在是给 AI 工具配。
先搞清楚：CLAUDE.md 有三个层级
CLAUDE.md 不是只有一个文件，它有三个层级，越具体的优先级越高：
| 层级 | 位置 | 作用范围 | 谁能用 | 典型内容 |
|---|---|---|---|---|
| 组织级 | /Library/Application Support/ClaudeCode/CLAUDE.md（macOS） | 整个组织的所有机器 | IT 部署 | 公司编码规范、安全策略 |
| 用户级 | ~/.claude/CLAUDE.md | 你机器上的所有项目 | 只有你 | 个人编码偏好、常用工具 |
| 项目级 | ./CLAUDE.md 或 ./.claude/CLAUDE.md | 当前项目 | 通过 git 共享给团队 | 技术栈、代码规范、常用命令 |
优先级：项目级 > 用户级 > 组织级。冲突时以更具体的层级为准。
另外还有一个本地覆盖层 .claude/CLAUDE.local.md，不会提交到 git，只在你自己机器上生效，用于存放个人在项目中的特殊偏好。
实际使用场景：
- 你是个 Vue 开发者，所有项目都用 pnpm → 写在用户级
~/.claude/CLAUDE.md - 某个项目用 Vue3 + TypeScript，禁止用
any→ 写在项目级./CLAUDE.md - 你本地跑测试需要先启动 Redis，但同事不需要 → 写在
.claude/CLAUDE.local.md
安全提醒：CLAUDE.md 不是权限系统
CLAUDE.md 是"给 AI 的建议"，不是强制约束，涉及安全时要警惕两点：
- 规则被更具体的层级放开：组织级写了"禁止调用某内部接口"，项目级却写了"允许调用"——项目级优先级更高，上级的禁令就失效了
- 提示注入：CLAUDE.md 本身也是上下文的一部分，一旦被恶意修改，AI 的行为约束随之改变
所以真正敏感的资源（密钥、核心目录、内部接口）要在 AI 之外用外围手段兜底：文件系统权限、接口级鉴权、settings.json 的 deny 规则（deny 在任何层级都无法被覆盖，见 06 章）。不能把安全完全寄托在"AI 听不听话"上。
怎么创建 CLAUDE.md
用 /init 让 Claude 自动生成（推荐）
/init 是 Claude Code 内置的一条命令，本质是一个精心设计的 prompt：让 Claude 扫描你的代码库，自动生成一份 CLAUDE.md。
基本用法：
/init
text
Claude 会读取你的 package.json、源码目录、配置文件等，自动生成内容包括：
- 常用命令（build、test、lint、dev 等怎么跑，怎么跑单个测试）
- 项目架构和目录结构（需要跨文件才能理解的"大图"）
- 技术栈和框架版本
如果 CLAUDE.md 已经存在，/init 不会覆盖，而是建议改进。
让 /init 输出中文：/init 本质是一段精心设计的 prompt，所以可以在命令后面直接追加自然语言要求：
/init 用中文生成，标注项目结构和核心代码入口
text
生成结果整体为中文，会标注项目结构和核心代码。即使残留部分英文也没关系——这个文件是给 AI 看的，不是给开发者看的。
交互式模式（更推荐）：
设置环境变量后，/init 会变成多步骤交互流程：
export CLAUDE_CODE_NEW_INIT=true
# 然后打开 Claude Code，输入 /init
bash
交互模式下 /init 会：
- 询问你要设置哪些配置（CLAUDE.md、Skills、Hooks）
- 用子代理深入扫描代码库
- 针对不确定的地方问你补充信息
- 生成方案让你确认后再写入
/init 能发现什么 vs 发现不了什么：
| 能自动发现 | 发现不了（需要你补充） |
|---|---|
| 构建和测试命令 | 你的编码习惯和偏好 |
| 技术栈和框架版本 | 业务领域的特殊约定 |
| 目录结构和文件组织 | 禁止事项（"不要用 any"） |
| 已有的 lint/eslint 配置 | 团队的隐性规范 |
所以正确的工作流是：
/init 生成基础版本 → 你手动补充 Claude 发现不了的规则 → 日常迭代
text
手动补充和调整
/init 只负责"从零到一"，后续的维护靠日常积累：
- 发现 Claude 老犯某个错 → 直接说"把这条加到 CLAUDE.md：组件样式必须用 scoped"
- 想调整规则 → 编辑
.claude/CLAUDE.md文件 - 规则太多太长 → 拆分到
.claude/rules/目录（见下文）
实战推荐工作流：把文件拖进会话，让 Claude 自己补。比手工编辑更顺手的做法是：把项目根目录的 CLAUDE.md 直接拖拽到 Claude Code 会话窗口（明确告诉它要改哪个文件），然后用一段自然语言描述你的约束，让它以结构化方式合并进去。一段可以直接复用的约束描述：
补充这个文档，加入以下团队规则：
1. 禁止删除 .git 等重要文件和核心目录
2. 禁止全局修改样式，组件样式必须 scoped
3. 项目如果没有初始化 git，先自动初始化再改代码
4. 使用 Vue / React 最新技术栈
5. 修改复杂功能前，先访问需要的细节信息，尽量使用 Plan 模式（Shift+Tab 切换）完成复杂功能
6. 创建文件及目录时，遵循良好的工程目录规范与命名规则
7. 在上面基础上，你可以继续扩展适合本项目的要求
text
Claude 会读取文件、思考后把"版本控制、技术栈、开发工作流、工程规范、组件结构、代码风格、提交规范"等章节结构化地补充进 CLAUDE.md。最后一条"你可以继续扩展"往往能带来惊喜——AI 会根据项目类型（前端/Python/Java）自动补齐对应规范的细则。
其中"Plan 模式"值得单独说一句：在 Claude Code 里按 Shift+Tab 可以切换到 plan mode——先规划、确认后再执行。大多数人没有先规划再动手的习惯，把"复杂功能用 Plan 模式"写进 CLAUDE.md，等于让 AI 替你守住这道关口。这些规则同样适用于 Codex 等其他 CLI 编码工具的规则文件，思路是通用的。
新项目没有代码怎么办
/init 依赖扫描代码库来生成内容，如果项目刚创建、还没有代码，就扫不出什么。这时候直接告诉 Claude 你要做什么项目，让它帮你生成：
帮我创建一个 Vue3 组件库项目，并生成 CLAUDE.md。要求：
- Vue 3.4 + TypeScript 5.3 + Vite 5.0 + PNPM
- 禁止用 any 类型
- 组件用 <script setup> 语法
- 用 Vitest 做测试，UnoCSS 做样式
- 提交代码前必须跑 lint 和 test
text
Claude 会同时帮你初始化项目和生成对应的 CLAUDE.md。之后代码写起来了，再跑一次 /init 补充 Claude 自己发现的规则。
简单说：有代码用 /init，没代码直接跟 Claude 说，说完了再 /init 补充。
CLAUDE.md 里写什么
不需要面面俱到，只写 Claude 经常做错的部分才有价值。官方建议控制在 200 行以内。
1. 项目概述和技术栈
## 项目概述
Vue 3 组件库开发教程项目。
技术栈：Vue 3.4+ | TypeScript 5.3+ | Vite 5.0+ | PNPM 8+
markdown
写具体版本号，不要只写"Vue 3"。Claude 会根据版本选择不同的 API。
2. 编码规范
这是最有价值的部分：
## 编码规范
- 禁止使用 `any` 类型，用 `unknown` 代替
- 组件 props 必须用 TypeScript 接口定义
- 组件必须使用 `<script setup>` 语法
- 事件处理函数用 `handle` 前缀（如 handleClick）
- 导出的类型单独放在 `types/` 目录
markdown
3. 禁止事项
比"应该怎么做"更重要的是"不要做什么"：
## 禁止事项
- 禁止直接修改 props（Vue 单向数据流）
- 禁止在组件中使用全局样式，必须 scoped
- 禁止使用已废弃 API（如 `::v-deep`）
markdown
4. 常用命令
## 常用命令
pnpm dev # 启动开发服务器
pnpm build # 构建
pnpm test # 跑测试
pnpm lint # 代码检查
markdown
5. 项目结构
## 项目结构
src/
components/ # 组件源码
Button/
index.ts # 导出入口
Button.vue # 组件实现
types.ts # 类型定义
utils/ # 工具函数
types/ # 公共类型
markdown
CLAUDE.md 是怎么加载的
Claude Code 启动时，从当前工作目录开始，向上逐级查找 CLAUDE.md 文件。
比如你在 foo/bar/ 目录下启动 Claude Code，它会依次加载：
foo/bar/CLAUDE.md（如果存在）foo/CLAUDE.md（如果存在）~/.claude/CLAUDE.md（用户级，始终加载）
项目级 .claude/rules/ 目录下的规则文件也会加载，没有 paths 限制的规则在启动时加载，有 paths 的规则在访问匹配文件时按需加载。
两个注意点：
- 修改 CLAUDE.md 后需要重启会话才能生效
- CLAUDE.md 不是强制执行的配置，是给 Claude 的"建议"。写得越具体，Claude 遵守得越好
文件太长怎么办
用 .claude/rules/ 拆分：
your-project/
├── .claude/
│ ├── CLAUDE.md # 主配置，放项目概述和常用命令
│ └── rules/
│ ├── code-style.md # 代码风格规范
│ ├── testing.md # 测试规范
│ └── security.md # 安全要求
text
rules 文件还支持 paths 前置配置，让规则只在特定文件类型下生效：
---
paths:
- "src/api/**/*.ts"
---
# API 开发规则
- 所有 API 端点必须包含输入验证
- 使用统一的错误响应格式
markdown
不用从零写：直接用现成的 Rules
社区已经有大量写好的 Rules 可以直接拿来用，没必要自己从头憋。
在线规则库：clauderules.net
clauderules.net 是一个社区维护的规则库网站，按语言/框架分类，可以直接复制粘贴到项目中：
| 分类 | 覆盖内容 |
|---|---|
| Next.js | App Router、Server Components、API 路由、Vercel 部署约定 |
| React | Hooks 使用、组件模式、状态管理、React 最佳实践 |
| TypeScript | 严格模式、类型模式、泛型、TS 特有约定 |
| Python | FastAPI、Django、Flask、类型提示、ruff/mypy/pytest |
| Node.js | Express、Fastify、NestJS、异步模式、项目结构 |
| Go | 惯用 Go 模式、错误处理、命名约定、Go Modules |
| Rust | 所有权约定、Result/Option 错误处理、Cargo workspace |
| Full-Stack | Monorepo、共享类型、前后端分离、跨栈模式 |
| General Coding | 代码风格、提交规范、测试模式、通用开发最佳实践 |
用法：打开网站，选你的技术栈，找到对应的规则，复制到 .claude/rules/ 目录即可。
GitHub 开源规则集合
| 仓库 | 特点 | 适合场景 |
|---|---|---|
| affaan-m/everything-claude-code | Anthropic 黑客马拉松冠军 10+ 个月日常实战沉淀的完整配置：CLAUDE.md + rules + agents + skills + hooks + commands + MCP 一应俱全，rules 按语言分目录（前端/Rust/Python/C#/C++/Java…），同一套配置兼容 Claude Code/Codex/Cursor/OpenCode/Gemini 等多个 harness | 需要一套完整、结构化的规则体系 |
| Lay4U/awesome-ai-rules | 为多种 AI 工具准备的规则（Claude Code/Cursor/Copilot/Windsurf），覆盖 TypeScript/React/Next.js/Python | 同时用多个 AI 编码工具 |
| DataGuy99/claude-code-rules | 31 条工作流规则，按开发流程组织（从会话开始到代码审查） | 想要一套完整的开发流程规范 |
| lazizbekshodmonov/claude-code-rules | 按项目类型分类的实战规则集 | 不同类型项目快速切换规范 |
直接安装示例
以 everything-claude-code 为例，它提供了一键安装脚本：
# 克隆仓库
git clone https://github.com/affaan-m/everything-claude-code.git
# 安装通用规则 + TypeScript 规则（适合前端项目）
cd everything-claude-code
./install.sh typescript
bash
安装后你的 ~/.claude/rules/ 目录结构：
~/.claude/rules/
├── common/ # 通用规则（所有项目生效）
│ ├── coding-style.md # 代码风格
│ ├── git-workflow.md # Git 工作流
│ ├── testing.md # 测试规范
│ ├── performance.md # 性能要求
│ ├── patterns.md # 设计模式
│ ├── hooks.md # Hooks 配置
│ ├── agents.md # Agent 规范
│ └── security.md # 安全要求
└── typescript/ # TypeScript 专属规则
├── coding-style.md # TS 代码风格（覆盖 common）
├── testing.md # TS 测试（Vitest/Jest）
└── ...
text
通用规则 + 语言专属规则组合使用：语言专属规则会覆盖同名的通用规则（比如 TypeScript 的编码风格会覆盖通用的编码风格）。
值得学习的是它的组织思路：主 CLAUDE.md 写得非常短——只说明这是个生产级插件、包含哪些 agents/skills/hooks/commands/rules/MCP 配置，具体内容全部分散到对应目录的文件里。这和".eslintrc 不写百页规则、按插件拆分"是同一个工程直觉。
推荐的 Rules 组合（前端项目）
如果你是前端开发者，建议这样配：
.claude/rules/
├── code-style.md # 从 clauderules.net 的 TypeScript 规则复制
├── vue-conventions.md # Vue3 相关约定（自己写或让 Claude 生成）
├── testing.md # 从 everything-claude-code 的 TypeScript 规则复制
└── git-workflow.md # 从 everything-claude-code 的 common 规则复制
text
重点：不要照搬整个仓库的规则。挑你实际需要的，不需要的别装——规则太多反而会降低 Claude 的遵守率。
引用外部文件
CLAUDE.md 支持 @path 语法引入其他文件：
# 项目概述见 README
@README
# 构建命令见 package.json
@package.json
# 个人偏好（不提交到 git）
@~/.claude/my-project-instructions.md
markdown
CLAUDE.md 的编写原则
/init 生成的只是基础版本，日常开发中你还需要手动补充和调整。CLAUDE.md 说白了就是给 Claude 写的"长期提示词"，每次对话都会自动加载。以下是几条判断规则写得好不好的原则：
原则一：具体可验证
# 差 —— 无法验证，Claude 不知道做到什么程度算"好"
保持代码简洁，遵循最佳实践。
# 好 —— 可以验证，做完没做完一目了然
- 文件不超过 800 行
- 组件文件用 PascalCase（Button.vue）
- 工具文件用 camelCase（formatDate.ts）
markdown
原则二：说为什么，不只说什么
# 差 —— 只说规则，Claude 遇到特殊情况可能会忽略
- 不要使用 emoji
# 好 —— 解释了原因，Claude 遇到类似场景会举一反三
- 不要使用 emoji：组件库会被其他项目引用，emoji 可能导致显示问题
markdown
原则三：用示例比用描述更有效
# 差 —— 纯文字描述
组件 props 必须用 TypeScript 接口定义。
# 好 —— 直接给示例，Claude 照着写就行
组件 props 必须这样定义：
```typescript
interface Props {
title: string
disabled?: boolean
}
const props = defineProps<Props>()
markdown
禁止这样写：defineProps({ title: String })
**原则四：多写"不要做什么"**
Claude 的默认行为已经很强了，它知道怎么写"正常"的代码。CLAUDE.md 的价值主要在纠正它做错的部分。所以"禁止事项"往往比"应该做的"更重要。
```markdown
## 禁止事项
- 禁止直接修改 props
- 禁止在提交信息中使用 emoji
- 禁止生成超过 200 行的文件（超过则主动拆分）
text
原则五：控制长度
官方建议 200 行以内。超过这个长度，Claude 的遵守率会明显下降。不是写得越多越好，而是写对的部分才有效。
工作流程建议
- 先
/init让 Claude 扫描项目，生成初始 CLAUDE.md - 根据上面的原则，手动补充 Claude 发现不了的规则（禁止事项、业务约定等）
- 日常开发中遇到 Claude 老犯某个错，直接说"把这条加到 CLAUDE.md"
- 定期回顾，删掉已经不需要的规则
调试要点
- Claude 没遵守规则：用
/memory检查文件是否被加载。没加载 = Claude 看不到 - 规则冲突：多层 CLAUDE.md 可能给出矛盾的指令，Claude 会随机选一个。检查是否有冲突
- 遵守率下降：文件超过 200 行时遵守率会降低，考虑拆分到
.claude/rules/
文档版本：v5.0 | 更新日期：2026-10-08参考来源：https://code.claude.com/docs/en/memory
↑